Transaction Initialization

This endpoint verifies that a customer exists in the Presto system and returns the necessary information to present a confirmation prompt to your users.

Overview

The wallet initialization endpoint is the first step in the wallet top-up process. It performs several critical functions:

• Validates that the provided identifier (phone, email, or user ID) belongs to a registered Presto user
• Verifies the customer's wallet status in the Presto registry
• Returns non-sensitive customer information for display in your confirmation interface
• Generates a unique transaction reference for tracking the top-up request

Endpoint Flow

The following diagram illustrates the wallet initialization process:

Endpoint Details

Method: POST
URL: /api/institutions/v1/wallet/init
Purpose: Initiate a wallet top-up request and validate customer information

Authentication Required

All API calls require a valid authentication token. Invalid or expired tokens will result in a 401 Unauthorized response.

Request Specification

Request Parameters

Parameter	Type	Required	Description
customer	object	Yes	Container for customer identification information
customer.identifier_type	string	Yes	Type of identifier being provided. Valid values: "phone", "email", "uid"
customer.identifier	string	Yes	The actual identifier value: • For "phone": E.164 format (country code + number, no leading "+") • For "email": Valid email address • For "uid": Presto user ID
amount	number	Yes	Amount to credit to the customer's wallet. Must be positive and support up to 3 decimal places
currency	string	Yes	Currency code for the amount. Currently supported: "LYD"

Identifier Format

When using phone numbers, ensure they are in E.164 format without the leading plus sign. For example, use "218920000000" instead of "+218920000000".

Example Request

// Headers:
// Authorization: Bearer {token}
// Content-Type: application/json

{
  "customer": {
    "identifier_type": "phone",
    "identifier": "218920000000"
  },
  "amount": 200.00,
  "currency": "LYD"
}

Response Specification

Success Response

200 OK

A successful response contains the transaction status, a unique transaction reference, and basic customer information for display.

{
  "data": {
    "status": "pending",
    "transaction_reference": "123FNS2Wsdsd3D",
    "customer": {
      "name": "MOH… OK…",
      "phone": "218920000000"
    },
    "ttl": "2025-05-25T18:49:51+00:00"
  }
}

Response Fields

Field	Type	Description
status	string	Current status of the transaction. Possible value: "pending"
transaction_reference	string	Unique identifier for the transaction to be used in subsequent API calls
customer	object	Customer information for display to the user
customer.name	string	Partially masked customer name for verification
customer.phone	string	Customer phone number
ttl	string	ISO 8601 timestamp when the transaction will expire (15 minutes from now)

Transaction Expiration

The ttl field indicates when the transaction will expire. If not confirmed within this period (15 minutes), the transaction will expire and you'll need to initialize a new one.

Error Responses

401 Unauthorized - Authentication issues

{
  "message": "Invalid or expired authentication token"
}

404 Not Found - Customer validation issues

{
  "message": "Customer not found"
}

422 Unprocessable Content - Input validation issues

{
  "message": "The customer.identifier_type field is required.",
  "errors": {
    "customer.identifier_type": [
      "The customer.identifier_type field is required."
    ]
  }
}

Error Handling

Common Errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Invalid or expired authentication token"}	Missing or invalid authentication token. Provide a valid token.
404	Customer not found	{"message": "Customer not found"}	The customer identifier does not match any user. Check the identifier.
422	Validation error	{"message": "The customer.identifier_type field is required.", "errors": { ... }}	Required fields are missing or invalid. Check the errors object for details.
500	Internal server error	{"message": "Failed to process request: ..."}	Unexpected server error. Try again or contact support.

Implementation Tips

Best Practices

• Always validate user input before making the API call
• Store the transaction reference securely for the confirmation step
• Display clear feedback to users when validation fails
• Consider implementing a countdown timer for the 15-minute validity period

Next Steps

After successfully initializing a wallet top-up, proceed to confirm the transaction using the Wallet Top-Up Confirmation endpoint with the returned transaction reference.

Transaction Expiration

Initialized transactions have a limited validity period. If not confirmed within this period (15 minutes), the transaction will expire and you'll need to initialize a new one.

For more information about the complete wallet top-up process, see Wallet Topup Flow Overview.